'\" t
.\"     Title: IPSEC_TTOSA
.\"    Author: Paul Wouters
.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
.\"      Date: 12/16/2012
.\"    Manual: Library functions
.\"    Source: libreswan
.\"  Language: English
.\"
.TH "IPSEC_TTOSA" "3" "12/16/2012" "libreswan" "Library functions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec_ttosa, ipsec_satot, ipsec_initsaid \- convert IPsec Security Association IDs to and from text, initialize an SA ID
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <libreswan\&.h>

typedef struct { ip_address dst; ipsec_spi_t spi; int proto; 
 } ip_said; 
.fi
.ft
.HP \w'const\ char\ *ttosa('u
.BI "const char *ttosa(const\ char\ *\ " "src" ", size_t\ " "srclen" ", ip_said\ *\ " "sa" ");"
.HP \w'size_t\ satot('u
.BI "size_t satot(const\ ip_said\ *\ " "sa" ", int\ " "format" ", char\ *\ " "dst" ", size_t\ " "dstlen" ");"
.HP \w'void\ initsaid('u
.BI "void initsaid(const\ ip_address\ *\ " "addr" ", ipsec_spi_t\ " "spi" ", int\ " "proto" ", ip_said\ *\ " "dst" ");"
.SH "DESCRIPTION"
.PP
\fITtosa\fR
converts an ASCII Security Association (SA) specifier into an
\fBip_said\fR
structure (containing a destination\-host address in network byte order, an SPI number in network byte order, and a protocol code)\&.
\fISatot\fR
does the reverse conversion, back to a text SA specifier\&.
\fIInitsaid\fR
initializes an
\fBip_said\fR
from separate items of information\&.
.PP
An SA is specified in text with a mail\-like syntax, e\&.g\&.
\fBesp\&.5a7@1\&.2\&.3\&.4\fR\&. An SA specifier contains a protocol prefix (currently
\fBah\fR,
\fBesp\fR,
\fBtun\fR,
\fBcomp\fR, or
\fBint\fR), a single character indicating the address family (\&.
for IPv4,
\fB:\fR
for IPv6), an unsigned integer SPI number in hexadecimal (with no
\fB0x\fR
prefix), and an IP address\&. The IP address can be any form accepted by
\fBipsec_ttoaddr\fR(3), e\&.g\&. dotted\-decimal IPv4 address, colon\-hex IPv6 address, or DNS name\&.
.PP
As a special case, the SA specifier
\fB%passthrough4\fR
or
\fB%passthrough6\fR
signifies the special SA used to indicate that packets should be passed through unaltered\&. (At present, these are synonyms for
\fBtun\&.0@0\&.0\&.0\&.0\fR
and
\fBtun:0@::\fR
respectively, but that is subject to change without notice\&.)
\fB%passthrough\fR
is a historical synonym for
\fB%passthrough4\fR\&. These forms are known to both
\fBttosa\fR
and
\fBsatot\fR, so the internal representation is never visible\&.
.PP
Similarly, the SA specifiers
\fB%pass\fR,
\fB%drop\fR,
\fB%reject\fR,
\fB%hold\fR,
\fB%trap\fR, and
\fB%trapsubnet\fR
signify special \(lqmagic\(rq SAs used to indicate that packets should be passed, dropped, rejected (dropped with ICMP notification), held, and trapped (sent up to
\fBipsec_pluto\fR(8), with either of two forms of
\fB%hold\fR
automatically installed) respectively\&. These forms too are known to both routines, so the internal representation of the magic SAs should never be visible\&.
.PP
The
\fB<libreswan\&.h>\fR
header file supplies the
\fBip_said\fR
structure, as well as a data type
\fBipsec_spi_t\fR
which is an unsigned 32\-bit integer\&. (There is no consistency between kernel and user on what such a type is called, hence the header hides the differences\&.)
.PP
The protocol code uses the same numbers that IP does\&. For user convenience, given the difficulty in acquiring the exact set of protocol names used by the kernel,
\fB<libreswan\&.h>\fR
defines the names
\fBSA_ESP\fR,
\fBSA_AH\fR,
\fBSA_IPIP\fR, and
\fBSA_COMP\fR
to have the same values as the kernel names
\fBIPPROTO_ESP\fR,
\fBIPPROTO_AH\fR,
\fBIPPROTO_IPIP\fR, and
\fBIPPROTO_COMP\fR\&.
.PP
\fB<libreswan\&.h>\fR
also defines
\fBSA_INT\fR
to have the value
61
(reserved by IANA for \(lqany host internal protocol\(rq) and
\fBSPI_PASS\fR,
\fBSPI_DROP\fR,
\fBSPI_REJECT\fR,
\fBSPI_HOLD\fR, and
\fBSPI_TRAP\fR
to have the values 256\-260 (in
\fIhost\fR
byte order) respectively\&. These are used in constructing the magic SAs (which always have address
0\&.0\&.0\&.0)\&.
.PP
If
\fBsatot\fR
encounters an unknown protocol code, e\&.g\&. 77, it yields output using a prefix showing the code numerically, e\&.g\&. \(lqunk77\(rq\&. This form is
\fInot\fR
recognized by
\fBttosa\fR\&.
.PP
The
\fIsrclen\fR
parameter of
\fBttosa\fR
specifies the length of the string pointed to by
\fIsrc\fR; it is an error for there to be anything else (e\&.g\&., a terminating NUL) within that length\&. As a convenience for cases where an entire NUL\-terminated string is to be converted, a
\fIsrclen\fR
value of
0
is taken to mean
\fBstrlen(src)\fR\&.
.PP
The
\fIdstlen\fR
parameter of
\fBsatot\fR
specifies the size of the
\fIdst\fR
parameter; under no circumstances are more than
\fIdstlen\fR
bytes written to
\fIdst\fR\&. A result which will not fit is truncated\&.
\fIDstlen\fR
can be zero, in which case
\fIdst\fR
need not be valid and no result is written, but the return value is unaffected; in all other cases, the (possibly truncated) result is NUL\-terminated\&. The
\fB<libreswan\&.h>\fR
header file defines a constant,
\fBSATOT_BUF\fR, which is the size of a buffer just large enough for worst\-case results\&.
.PP
The
\fIformat\fR
parameter of
\fBsatot\fR
specifies what format is to be used for the conversion\&. The value
0
(not the ASCII character
\fB\*(Aq0\*(Aq\fR, but a zero value) specifies a reasonable default (currently lowercase protocol prefix, lowercase hexadecimal SPI, dotted\-decimal or colon\-hex address)\&. The value
\fB\*(Aqf\*(Aq\fR
is similar except that the SPI is padded with
0s to a fixed 32\-bit width, to ease aligning displayed tables\&.
.PP
\fITtosa\fR
returns
\fBNULL\fR
for success and a pointer to a string\-literal error message for failure; see DIAGNOSTICS\&.
\fISatot\fR
returns
0
for a failure, and otherwise always returns the size of buffer which would be needed to accommodate the full conversion result, including terminating NUL; it is the caller\*(Aqs responsibility to check this against the size of the provided buffer to determine whether truncation has occurred\&.
.PP
There is also, temporarily, support for some obsolete forms of SA specifier which lack the address\-family indicator\&.
.SH "SEE ALSO"
.PP
\fBipsec_ttoul\fR(3),
\fBipsec_ttoaddr\fR(3),
\fBipsec_samesaid\fR(3),
\fBinet\fR(3)
.SH "DIAGNOSTICS"
.PP
Fatal errors in
\fBttosa\fR
are: empty input; input too small to be a legal SA specifier; no
\fB@\fR
in input; unknown protocol prefix; conversion error in
\fIttoul\fR
or
\fIttoaddr\fR\&.
.PP
Fatal errors in
\fBsatot\fR
are: unknown format\&.
.SH "HISTORY"
.PP
Written for the FreeS/WAN project by Henry Spencer\&.
.SH "BUGS"
.PP
The restriction of text\-to\-binary error reports to literal strings (so that callers don\*(Aqt need to worry about freeing them or copying them) does limit the precision of error reporting\&.
.PP
The text\-to\-binary error\-reporting convention lends itself to slightly obscure code, because many readers will not think of NULL as signifying success\&. A good way to make it clearer is to write something like:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBconst char *error;\fR

\fBerror = ttosa( /* \&.\&.\&. */ );\fR
\fBif (error != NULL) {\fR
\fB        /* something went wrong */\fR
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.PP
\fBPaul Wouters\fR
.RS 4
placeholder to suppress warning
.RE
